Hide agentserver response internals from API surface by Shivakishore14 · Pull Request #48370 · Azure/azure-sdk-for-python

Shivakishore14 · 2026-07-30T16:23:00Z

Addresses the APIView feedback from PR #47995 by tightening the azure-ai-agentserver-responses public API surface while preserving contract-bearing types.

Changes:

Removes root-level public helper leaks from azure.ai.agentserver.responses:
- get_conversation_id
- to_output_item
Keeps the model expansion helpers public under azure.ai.agentserver.responses.models for SDK parity:
- get_content_expanded
- get_conversation_expanded
- get_conversation_id
- get_input_expanded
- get_tool_choice_expanded
Moves validation-only error plumbing from models.errors to private models._errors.
- Public wire models models.ApiErrorResponse and models.Error remain unchanged.
- The nested ApiErrorResponse.error: Error shape is preserved.
Keeps models.runtime public because ResponseExecution, ResponseModeFlags, and StreamEventRecord appear in public signatures.
Hides implementation-only runtime helpers by renaming them with leading underscores inside models.runtime:
- _build_cancelled_response
- _build_failed_response
- _apply_cancelled_terminal
- _apply_failed_terminal
- _resolve_cancelled_response
- _resolve_failed_response
- _StreamReplayState
Removes duplicate generated model aliases from the public models.runtime API surface.
Adds 2.0.0b1 changelog/version entry for this API cleanup.
Regenerates api.md and api.metadata.yml.

Validation:

azpysdk apistub .
azsdk_package_build_code (Python build no-op)
azsdk_package_run_check with Linting
Focused pytest suite: 246 passed, 1 warning

Move response contracts to local TypedDict wire payloads and remove runtime reliance on generated model constructors, serialization helpers, and nested generated SDK model paths. Keep validation behind a stable local wrapper and update tests to exercise dict-native payloads instead of generated model runtime callability. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Use the source-built TypeSpec Python emitter TypedDict output as the model source instead of the localized bridge artifact. Normalize the emitted package into the local AgentServer generated boundary and remove fake model_base/_models compatibility shims. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Pin AgentServer TypeSpec generation to the source PR that removes stale OpenAI usage decorators and enables Python TypeDict generation. Replace the old finalization script with a minimal contract extractor, regenerate API docs and model contracts, and remove unused _types.py output. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Regenerate AgentServer response TypedDict contracts, validators, and API docs from the current AgentServer service contract path. Point tsp-location.yaml at the fresh spec PR commit and compile from the clean synced Foundry/src root. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Inline the single-use wire field mutation helper and remove a thin Foundry serializer wrapper that only delegated to to_wire_dict. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

…peddict-local

Generate the TypedDict enum fallback at the root _generated package so validators use the same _enums import shape as latest main. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Point AgentServer Responses generation metadata at the latest spec PR commit after CI-only validation fixes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Address runtime dict-native response compatibility, static analysis, spelling, and Sphinx documentation failures for the AgentServer Responses package. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Update samples to use TypedDict-safe access and required discriminator fields so package Pyright validation passes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Regenerate AgentServer response contracts from the rapida/add-agentserver-view spec branch and restore the SDK TypeSpec pointer layout to the main SDK shape with only the commit updated. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Fix review feedback for dict-native response models by completing ID generation coverage, preserving wire field names, filtering storage-only SSE fields, and restoring ResponseIncompleteReason as a public compatibility enum. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Sanitize generated model docstrings that Sphinx treats as warnings, narrow public model exports to actual generated types, and add package spellcheck words for generated response ID prefixes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Avoid using generated enum fallback objects in runtime code by comparing against the stable wire string values directly, and annotate the ID dispatch table for mypy. Regenerate API stubs after the public export cleanup. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Handle scale service tier validation, tighten input text extraction, preserve required statuses on search output items, reject output-only item types from input conversion, and keep generated union aliases public without exposing enum literal aliases. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Use a correctly spelled invalid enum member name in the generated enum fallback regression test so CSpell does not flag the test-only typo. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Generate runtime enum classes from literal aliases so enum members preserve isinstance and iteration semantics, and materialize response timestamps as Unix integers in emitted wire payloads. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Move custom request validators out of the TypeSpec-emitted _generated package and align validation helper names with TypedDict Literal contracts instead of enum shims. Preserve scale service_tier support by reading the generated CreateResponse field literal before schema alias fallback. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Update the AgentServer responses SDK to consume the spec fix that removes the server-assigned id field from function-call input items. Regenerate TypedDict contracts, request validators, and API stubs, and add a checked typing contract for CreateResponse function-call input without id. Spec PR: Azure/azure-rest-api-specs#44927 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Update the AgentServer responses TypeSpec pin to the spec PR tip that includes the function-call input id fix and CI metadata for the SDK-only contracts folder. Spec PR: Azure/azure-rest-api-specs#44927 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Enforce generated Literal aliases for enum-like schemas, reject unknown discriminators, preserve nullable literal refs, export public Literal aliases, and clean generated validator/temp outputs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Copilot

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated no new comments.

Suppressed comments (2)

sdk/agentserver/azure-ai-agentserver-responses/azure/ai/agentserver/responses/models/runtime.py:344

Prefixing these two builders with _ does not perform the described move of runtime helpers/state to a private module. models/runtime.py remains public, and the regenerated API still exposes the resolver/apply helpers plus ResponseExecution, ResponseModeFlags, StreamEventRecord, and StreamReplayState under models.runtime (api.md:5924-6124). Move this implementation to models._runtime, update its imports/docs/tests, and regenerate the API artifacts.

def _build_cancelled_response(

sdk/agentserver/azure-ai-agentserver-responses/api.metadata.yml:1

The regenerated surface still exposes azure.ai.agentserver.responses.models.get_content_expanded at api.md:1755 because models/__init__.py continues to import it and list it in __all__. This contradicts the PR's stated removal; remove those export entries and regenerate both API artifacts.

apiMdSha256: 791aa262be4b10719e1a9ddde5516041bdad4d169806f83d5ebaef26474ccb30

Keep contract-bearing runtime types public, but move terminal response helpers and replay state to the private models._runtime module. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated no new comments.

Suppressed comments (1)

sdk/agentserver/azure-ai-agentserver-responses/CHANGELOG.md:8

This release note understates a breaking API change: the public models.errors/models.runtime members are removed, and responses.__init__ also drops the root-level get_conversation_id and to_output_item exports without mentioning them. This package records public removals under ### Breaking Changes (see this file at lines 83–88), so please classify and enumerate these removals rather than presenting them as an unspecified cleanup.

- Cleaned up the public API surface by moving validation-only error helpers and runtime terminal/replay helpers to private implementation modules.

Remove the separate models._runtime module and keep implementation-only runtime helpers in models.runtime with leading underscores. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Add Azure-style parameter and return documentation required by pylint for private runtime helpers. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…blic-surface' into sshiva/agentserver-api-review-public-surface

azure-pipelines · 2026-08-03T19:55:57Z

Azure Pipelines: Successfully started running 1 pipeline(s). 9 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run.

azure-pipelines · 2026-08-03T19:58:44Z

Azure Pipelines: Successfully started running 1 pipeline(s). 9 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run.

Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated no new comments.

Suppressed comments (1)

sdk/agentserver/azure-ai-agentserver-responses/CHANGELOG.md:7

This release also removes the public top-level get_conversation_id and to_output_item exports, so existing imports will fail, but the changelog only calls out the error/runtime changes. Please list these removals explicitly so the breaking API change is discoverable.

- Cleaned up the public API surface by moving validation-only error helpers to a private implementation module and renaming runtime terminal/replay helpers as private.

github-actions · 2026-08-03T20:27:05Z

[Pilot] PR Pipeline Failure Analysis

A CI pipeline failed on this pull request. Here is an automated analysis of what went wrong and how to get the build green.

What failed

One test is consistently failing across 5 platform/build matrix combinations (macOS Python 3.11, Ubuntu Python 3.12 sdist & whl, Ubuntu Python 3.13 sdist & whl, Ubuntu Python 3.14 whl):

tests.e2e.resilience_contract.test_row_1_path_b.test_row_1_path_b_graceful_exit_not_sigkill

The failure is in the azure-ai-agentserver-responses package's end-to-end resilience contract test, specifically the "graceful exit (not SIGKILL)" path. The consistent reproduction across all OS/Python-version/package-format combinations suggests a test failure tied to a real behavioral regression introduced by this PR's API surface changes, rather than an infrastructure flake.

Recommended next steps

Reproduce the failure locally: pytest tests/e2e/resilience_contract/test_row_1_path_b.py -k test_row_1_path_b_graceful_exit_not_sigkill -v
Review whether the internal renaming of _build_cancelled_response, _build_failed_response, _apply_cancelled_terminal, _apply_failed_terminal, _resolve_cancelled_response, _resolve_failed_response, and _StreamReplayState (all now prefixed with _) inadvertently broke the graceful-exit/cancellation path exercised by this test.
Check that any code inside the resilience contract test (or the runtime code it exercises) still correctly references the renamed symbols.
Once fixed, push a new commit — the CI will re-run automatically.
See the CI troubleshooting guide: https://aka.ms/ci-fix
Push new commits to address the failures; this comment updates automatically on the next failing run.

Raw pipeline analysis (azsdk ci analyze)

Analyzing pipeline https://github.com/Azure/azure-sdk-for-python/pull/48370...
--------------------------------------------------------------------------------
Failed Tests
--------------------------------------------------------------------------------
{
  "/tmp/6652601/LLM Artifacts - macos311 - 1/agentserver-azure-ai-agentserver-responses-test-junit-whl.xml": [
    "tests.e2e.resilience_contract.test_row_1_path_b.test_row_1_path_b_graceful_exit_not_sigkill"
  ],
  "/tmp/6652601/LLM Artifacts - Ubuntu2404_313 - 1/agentserver-azure-ai-agentserver-responses-test-junit-sdist.xml": [
    "tests.e2e.resilience_contract.test_row_1_path_b.test_row_1_path_b_graceful_exit_not_sigkill"
  ],
  "/tmp/6652601/LLM Artifacts - ubuntu2404_312 - 1/agentserver-azure-ai-agentserver-responses-test-junit-sdist.xml": [
    "tests.e2e.resilience_contract.test_row_1_path_b.test_row_1_path_b_graceful_exit_not_sigkill"
  ],
  "/tmp/6652601/LLM Artifacts - ubuntu2404_312 - 1/agentserver-azure-ai-agentserver-responses-test-junit-whl.xml": [
    "tests.e2e.resilience_contract.test_row_1_path_b.test_row_1_path_b_graceful_exit_not_sigkill"
  ],
  "/tmp/6652601/LLM Artifacts - Ubuntu2404_314 - 1/agentserver-azure-ai-agentserver-responses-test-junit-whl.xml": [
    "tests.e2e.resilience_contract.test_row_1_path_b.test_row_1_path_b_graceful_exit_not_sigkill"
  ]
}

Copilot detected the failing pipeline and generated the analysis above. To have it attempt a fix automatically, reply with `@copilot please fix the failing pipeline on this PR`.

Generated by Pipeline Analysis - Next Steps · 19.5 AIC · ⌖ 8.81 AIC · ⊞ 6.6K · ◷

…i-review-public-surface

…i-review-public-surface # Conflicts: # sdk/agentserver/azure-ai-agentserver-responses/api.metadata.yml

Treat the response context shutdown signal as authoritative when a resilient background handler returns without terminal output, so graceful shutdown hands off to recovery instead of hanging until SIGKILL. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated no new comments.

Suppressed comments (3)

sdk/agentserver/azure-ai-agentserver-responses/azure/ai/agentserver/responses/models/runtime.py:15

Moving these generated types behind TYPE_CHECKING makes the annotations on the public ResponseExecution and StreamEventRecord APIs unresolvable at runtime. For example, typing.get_type_hints(ResponseExecution.__init__) now evaluates ResponseObject, OutputItem, and AgentReference against this module and raises NameError because none of them exists in its globals. Import the generated module under a private alias and qualify these annotations (or otherwise keep their runtime names resolvable) so the aliases stay out of APIView without breaking runtime type introspection.

    from ._generated import AgentReference, OutputItem, ResponseObject, ResponseStreamEvent

sdk/agentserver/azure-ai-agentserver-responses/CHANGELOG.md:7

This release note does not disclose the two root-level API removals made by this PR. Existing users importing get_conversation_id or to_output_item from azure.ai.agentserver.responses will break on upgrade, so name those removals explicitly (and point out that get_conversation_id remains under models).

- Cleaned up the public API surface by moving validation-only error helpers to a private implementation module and renaming runtime terminal/replay helpers as private.

sdk/agentserver/azure-ai-agentserver-responses/azure/ai/agentserver/responses/hosting/_resilient_orchestrator.py:882

This introduces a resilient-execution behavior change that is not described by this API-surface cleanup: setting only the handler-facing context.shutdown event now forces ctx.exit_for_recovery() and leaves a nonterminal task in progress. Please either move this shutdown fix to a focused change or document it here and add a regression test that verifies the resulting persisted/recovery state; the existing tests that manually set context.shutdown only assert emitted events, not this new task-state transition.

            shutdown_requested = ctx.shutdown.is_set() or (context is not None and context.shutdown.is_set())
            if shutdown_requested and record is not None and record.status in {"queued", "in_progress"}:

Shivakishore14 and others added 30 commits July 10, 2026 11:01

Reduce redundant agentserver wire conversions

2e9a3b1

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Merge remote-tracking branch 'origin/main' into sshiva/agentserver-ty…

039fbd2

…peddict-local

Sync AgentServer spec pointer

e97042d

Point AgentServer Responses generation metadata at the latest spec PR commit after CI-only validation fixes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Fix AgentServer Responses sample typing

01233dd

Update samples to use TypedDict-safe access and required discriminator fields so package Pyright validation passes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Merge branch 'main' into sshiva/agentserver-typeddict-local

6fe830f

Address AgentServer review and API consistency

92db0e3

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Fix AgentServer stream TTL contract tests

1ec49f6

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Hide internal AgentServer message models

34b2061

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Remove AgentServer generated enum shim

26383d8

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Merge branch 'main' into sshiva/agentserver-typeddict-local

af85d78

Merge branch 'main' into sshiva/agentserver-typeddict-local

2762371

Fix agentserver generated docs warnings

adc5760

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4ead3de5-a3b3-4d3a-bf93-a4ee397d7498

Copilot AI reviewed Aug 3, 2026

View reviewed changes

Move runtime helpers out of public surface

a38393c

Keep contract-bearing runtime types public, but move terminal response helpers and replay state to the private models._runtime module. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings August 3, 2026 17:32

Shivakishore14 marked this pull request as draft August 3, 2026 17:32

Copilot started reviewing on behalf of Shivakishore14 August 3, 2026 17:32 View session

Copilot AI reviewed Aug 3, 2026

View reviewed changes

Shivakishore14 and others added 4 commits August 3, 2026 18:29

Keep runtime helpers private in runtime module

10805eb

Remove the separate models._runtime module and keep implementation-only runtime helpers in models.runtime with leading underscores. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Merge branch 'main' into sshiva/agentserver-api-review-public-surface

37dd7d9

Fix runtime helper docstrings

25d80d0

Add Azure-style parameter and return documentation required by pylint for private runtime helpers. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Merge remote-tracking branch 'origin/sshiva/agentserver-api-review-pu…

742f535

…blic-surface' into sshiva/agentserver-api-review-public-surface

Shivakishore14 marked this pull request as ready for review August 3, 2026 19:55

Copilot AI review requested due to automatic review settings August 3, 2026 19:55

Copilot started reviewing on behalf of Shivakishore14 August 3, 2026 19:56 View session

Shivakishore14 marked this pull request as draft August 3, 2026 19:57

Shivakishore14 marked this pull request as ready for review August 3, 2026 19:58

Copilot AI reviewed Aug 3, 2026

View reviewed changes

ankitbko approved these changes Aug 4, 2026

View reviewed changes

Shivakishore14 and others added 3 commits August 4, 2026 06:36

Merge remote-tracking branch 'origin/main' into sshiva/agentserver-ap…

422d9d6

…i-review-public-surface

Merge remote-tracking branch 'origin/main' into sshiva/agentserver-ap…

5a45a65

…i-review-public-surface # Conflicts: # sdk/agentserver/azure-ai-agentserver-responses/api.metadata.yml

Copilot AI review requested due to automatic review settings August 4, 2026 06:50

Copilot started reviewing on behalf of Shivakishore14 August 4, 2026 06:51 View session

Copilot AI reviewed Aug 4, 2026

View reviewed changes

Shivakishore14 enabled auto-merge (squash) August 4, 2026 07:50

ankitbko approved these changes Aug 4, 2026

View reviewed changes

Shivakishore14 merged commit 615720d into main Aug 4, 2026
21 checks passed

Shivakishore14 deleted the sshiva/agentserver-api-review-public-surface branch August 4, 2026 09:06

Navigation Menu

Uh oh!

Hide agentserver response internals from API surface - #48370

Hide agentserver response internals from API surface#48370
Shivakishore14 merged 49 commits into
mainfrom
sshiva/agentserver-api-review-public-surface

Shivakishore14 commented Jul 30, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

azure-pipelines Bot commented Aug 3, 2026

Uh oh!

azure-pipelines Bot commented Aug 3, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

github-actions Bot commented Aug 3, 2026

What failed

Recommended next steps

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

Shivakishore14 commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

azure-pipelines Bot commented Aug 3, 2026

Uh oh!

azure-pipelines Bot commented Aug 3, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

github-actions Bot commented Aug 3, 2026

What failed

Recommended next steps

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Shivakishore14 commented Jul 30, 2026 •

edited

Loading